Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Flattening and Unflattening Shape Objects

GXUnflattenShape

You can use the GXUnflattenShape function to restore the object form of a shape--including all the objects that it references--from a stream-based description created by the GXFlattenShape function.

gxShape GXUnflattenShape(struct gxSpoolBlock *block, long count, 
                        const gxViewPort portList[])

block

A pointer to a spool block structure. QuickDraw GX uses information in the spool block to unflatten the data.

count

The number of view ports in the view port list (the number of elements in the portList array).

portList

An array of references to view port objects. It is the list of view ports to assign to the transform object for the unflattened shape.

function result

A reference to the newly created (unflattened) shape.

DESCRIPTION

The GXUnflattenShape function reconstructs a shape object and all its associated objects from stream data in a buffer pointed to by the spool block specified in the block parameter.

Before calling GXUnflattenShape, you need to allocate a spool block structure and buffer to hold the flattened data, and place a pointer to the buffer and a specification
of its size into the spool block. You also place into the spool block a pointer to an application-defined spool function that reads the flattened data into the buffer. The spool function responds to commands from QuickDraw GX to open, read, and close the file containing the flattened data.

Note that unflattening a shape also causes creation of all its referenced objects, such as its style, ink, and transform, and all of their referenced objects. Unflattening a picture can cause the creation of many shape objects.

The flattened stream as read by GXUnflattenShape consists of a series of opcodes and associated data, following the QuickDraw GX stream format.

SPECIAL CONSIDERATIONS

If no error occurs, the GXUnflattenShape function creates one or more QuickDraw GX objects. You are responsible for disposing of those objects when you no longer need them.

If the spool function signals an error during either flattening or unflattening, QuickDraw GX posts an unflattening_interrupted_by_client error. If the
spool function attempts to call GXUnflattenShape, QuickDraw GX posts a procedure_not_reentrant error.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
procedure_not_reentrant
parameter_is_nil	(debugging version)
spoolProcedure_is_nil
unflattening_interrupted_by_client
font_not_found
parameter_out_of_range	(debugging version)
inconsistent_parameters	(debugging version)
Warnings
unrecognized_stream_version
bad_data_in_stream

SEE ALSO

The spool block structure is described on page 2-49. The format for the application-defined spool function is described on page 2-91.

The format for the flattened data, including all opcodes, is described in the stream format chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

To convert a QuickDraw GX shape to its flattened form, use the GXFlattenShape function, described in the previous section.